image: align erofs raw/zstd convert behavior with containerd by ChengyuZhu6 · Pull Request #4927 · containerd/nerdctl

ChengyuZhu6 · 2026-05-22T02:49:12Z

sathiraumesh · 2026-05-23T07:42:07Z

if there are no others it looks okay to me

ChengyuZhu6 · 2026-06-21T13:57:23Z

# nerdctl image convert --erofs zstd env12.com/library/ubuntu:20.04 env12.com/library/ubuntu:20.04-erofs-0621-zstd
WARN[0000] option --erofs should be used in conjunction with --oci 
env12.com/library/ubuntu:20.04-erofs-0621-zstd:                                   resolved     env12.com/library/ubuntu:20.04-erofs-0621-zstd:                                   resolved       |++++++++++++++++++++++++++++++++++++++| index-sha256:121726370cec48ffa4fc006c3f75d5cd0835b6b97586119023a7068e7906d0b7:    exists         |++++++++++++++++++++++++++++++++++++++| manifest-sha256:c664f8f86ed5a386b0a340d981b8f81714e21a8b9c73f658c4bea56aa179d54a: exists         |++++++++++++++++++++++++++++++++++++++| config-sha256:b7bab04fd9aa0c771e5720bf0cc7cbf993fd6946645983d9096126e5af45d713:   exists         |++++++++++++++++++++++++++++++++++++++| layer-sha256:13b7e930469f6d3575a320709035c6acf6f5485a76abcf03d1b92a64c09c2476:    exists         |++++++++++++++++++++++++++++++++++++++| elapsed: 2.9 s                                                                    total:   0.0 B (0.0 B/s)
# nerdctl push env12.com/library/ubuntu:20.04-erofs-0621-zstdINFO[0000] pushing as a reduced-platform image (application/vnd.oci.image.index.v1+json, sha256:6d253ab5bee747c31e242be763d43a8fae579f66d45ef4fe9e981059bdbd0e0a) 
index-sha256:6d253ab5bee747c31e242be763d43a8fae579f66d45ef4fe9e981059bdbd0e0a:    done           |++++++++++++++++++++++++++++++++++++++| 
manifest-sha256:bbff53e6a6c1e7fa4f9a937721d80a530f7fab85e2c1b9c013b1de1432bf4ea7: done           |++++++++++++++++++++++++++++++++++++++| 
layer-sha256:be3e928c0084a1279b86d771cd8c9d75a9d7e90295131c3757388c6bac9c4084:    done           |++++++++++++++++++++++++++++++++++++++| 
config-sha256:5824adab6cbce42ae826a50d419493c49447f9c827d83e24eec2138c3b620c7f:   done           |++++++++++++++++++++++++++++++++++++++| 
elapsed: 4.3 s                                                                    total:  23.2 M (5.4 MiB/s)
                                         
# nerdctl image convert --erofs raw env12.com/library/ubuntu:20.04 env12.com/library/ubuntu:20.04-erofs-0621
WARN[0000] option --erofs should be used in conjunction with --oci 
env12.com/library/ubuntu:20.04-erofs-0621:                                        resolved     env12.com/library/ubuntu:20.04-erofs-0621:                                        resolved       |++++++++++++++++++++++++++++++++++++++| index-sha256:121726370cec48ffa4fc006c3f75d5cd0835b6b97586119023a7068e7906d0b7:    exists         |++++++++++++++++++++++++++++++++++++++| manifest-sha256:c664f8f86ed5a386b0a340d981b8f81714e21a8b9c73f658c4bea56aa179d54a: exists         |++++++++++++++++++++++++++++++++++++++| config-sha256:b7bab04fd9aa0c771e5720bf0cc7cbf993fd6946645983d9096126e5af45d713:   exists         |++++++++++++++++++++++++++++++++++++++| layer-sha256:13b7e930469f6d3575a320709035c6acf6f5485a76abcf03d1b92a64c09c2476:    exists         |++++++++++++++++++++++++++++++++++++++| elapsed: 3.2 s                                                                    total:   0.0 B (0.0 B/s)
# nerdctl push env12.com/library/ubuntu:20.04-erofs-0621INFO[0000] pushing as a reduced-platform image (application/vnd.oci.image.index.v1+json, sha256:46e3aed7bc082f2386106b7b3ac50089457840ab8717277941cfe94e32f96bdd) 
index-sha256:46e3aed7bc082f2386106b7b3ac50089457840ab8717277941cfe94e32f96bdd:    done           |++++++++++++++++++++++++++++++++++++++| 
manifest-sha256:7cfe388d681e8e39f44b025387f53fafc6bef12a95fda9561755d915347276ba: done           |++++++++++++++++++++++++++++++++++++++| 
layer-sha256:34c9cce61ef84e29d092a45e64069667c7e3542e8481d4fe8725bb774bcd6167:    done           |++++++++++++++++++++++++++++++++++++++| 
config-sha256:62184158ea39ddb98ae7df5c55ad73df8a0a9f6110f594db0bbe01b1224ee560:   done           |++++++++++++++++++++++++++++++++++++++| 
elapsed: 8.0 s                                                                    total:  75.9 M (9.5 MiB/s)

ChengyuZhu6 · 2026-06-21T13:59:00Z

# nerdctl manifest inspect env12.com/library/ubuntu:20.04-erofs-0621-zstd
{
    "schemaVersion": 2,
    "mediaType": "application/vnd.oci.image.index.v1+json",
    "manifests": [
        {
            "mediaType": "application/vnd.oci.image.manifest.v1+json",
            "digest": "sha256:bbff53e6a6c1e7fa4f9a937721d80a530f7fab85e2c1b9c013b1de1432bf4ea7",
            "size": 399,
            "annotations": {
                "com.docker.official-images.bashbrew.arch": "amd64",
                "org.opencontainers.image.base.name": "scratch",
                "org.opencontainers.image.created": "2025-04-04T00:00:00Z",
                "org.opencontainers.image.revision": "fb4da0956290c3b216a35315510f66ca9bc4a460",
                "org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
                "org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
                "org.opencontainers.image.version": "20.04"
            },
            "platform": {
                "architecture": "amd64",
                "os": "linux",
                "os.features": [
                    "erofs"
                ]
            }
        }
    ]
}
# nerdctl manifest inspect env12.com/library/ubuntu@sha256:bbff53e6a6c1e7fa4f9a937721d80a530f7fab85e2c1b9c013b1de1432bf4ea7
{
    "schemaVersion": 2,
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "config": {
        "mediaType": "application/vnd.oci.image.config.v1+json",
        "digest": "sha256:5824adab6cbce42ae826a50d419493c49447f9c827d83e24eec2138c3b620c7f",
        "size": 2029
    },
    "layers": [
        {
            "mediaType": "application/vnd.erofs.layer.v1+zstd",
            "digest": "sha256:be3e928c0084a1279b86d771cd8c9d75a9d7e90295131c3757388c6bac9c4084",
            "size": 24365791
        }
    ]
}

# nerdctl manifest inspect env12.com/library/ubuntu:20.04-erofs-0621
{
    "schemaVersion": 2,
    "mediaType": "application/vnd.oci.image.index.v1+json",
    "manifests": [
        {
            "mediaType": "application/vnd.oci.image.manifest.v1+json",
            "digest": "sha256:7cfe388d681e8e39f44b025387f53fafc6bef12a95fda9561755d915347276ba",
            "size": 394,
            "annotations": {
                "com.docker.official-images.bashbrew.arch": "amd64",
                "org.opencontainers.image.base.name": "scratch",
                "org.opencontainers.image.created": "2025-04-04T00:00:00Z",
                "org.opencontainers.image.revision": "fb4da0956290c3b216a35315510f66ca9bc4a460",
                "org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
                "org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
                "org.opencontainers.image.version": "20.04"
            },
            "platform": {
                "architecture": "amd64",
                "os": "linux",
                "os.features": [
                    "erofs"
                ]
            }
        }
    ]
}
# nerdctl manifest inspect env12.com/library/ubuntu@sha256:7cfe388d681e8e39f44b025387f53fafc6bef12a95fda9561755d915347276ba
{
    "schemaVersion": 2,
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "config": {
        "mediaType": "application/vnd.oci.image.config.v1+json",
        "digest": "sha256:62184158ea39ddb98ae7df5c55ad73df8a0a9f6110f594db0bbe01b1224ee560",
        "size": 2029
    },
    "layers": [
        {
            "mediaType": "application/vnd.erofs.layer.v1",
            "digest": "sha256:34c9cce61ef84e29d092a45e64069667c7e3542e8481d4fe8725bb774bcd6167",
            "size": 79568896
        }
    ]
}

ChengyuZhu6 · 2026-06-21T13:59:54Z

# nerdctl image pull --snapshotter erofs  env12.com/library/ubuntu:20.04-erofs-0621
env12.com/library/ubuntu:20.04-erofs-0621       saved
└──index-sha256:46e3aed7bc082f2386106b7b        complete        |++++++++++++++++++++++++++++++++++++++|
   └──manifest-sha256:7cfe388d681e8e39f4        complete        |++++++++++++++++++++++++++++++++++++++|
      ├──config-sha256:62184158ea39ddb98        complete        |++++++++++++++++++++++++++++++++++++++|
      └──layer-sha256:34c9cce61ef84e29d0        complete        |++++++++++++++++++++++++++++++++++++++|
application/vnd.oci.image.index.v1+json sha256:46e3aed7bc082f2386106b7b3ac50089457840ab8717277941cfe94e32f96bdd
Completed pull from OCI Registry (env12.com/library/ubuntu:20.04-erofs-0621)    elapsed: 7.6 stotal:  75.9 M   (10.0 MiB/s)

# nerdctl image pull --snapshotter erofs  env12.com/library/ubuntu:20.04-erofs-0621-zstd
env12.com/library/ubuntu:20.04-erofs-0621-zstd  saved
└──index-sha256:6d253ab5bee747c31e242be7        complete        |++++++++++++++++++++++++++++++++++++++|
   └──manifest-sha256:bbff53e6a6c1e7fa4f        complete        |++++++++++++++++++++++++++++++++++++++|
      ├──config-sha256:5824adab6cbce42ae        complete        |++++++++++++++++++++++++++++++++++++++|
      └──layer-sha256:be3e928c0084a1279b        complete        |++++++++++++++++++++++++++++++++++++++|
application/vnd.oci.image.index.v1+json sha256:6d253ab5bee747c31e242be763d43a8fae579f66d45ef4fe9e981059bdbd0e0a
Completed pull from OCI Registry (env12.com/library/ubuntu:20.04-erofs-0621-zstd)       elapsed: 3.7 s total:  23.2 M  (6.3 MiB/s)

Copilot

Pull request overview

This PR adds EROFS image conversion support (raw and zstd) and adjusts platform matching/transfer behavior to better align EROFS raw/zstd handling with containerd (#4861).

Changes:

Add nerdctl image convert --erofs {raw|zstd} support (including option wiring and docs).
Adjust platform matching and transfer platform selection to tolerate/emit os.features=["erofs"] variants.
Ensure push ref-key behavior works for EROFS layer media types; add basic conversion test coverage.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pkg/platformutil/platformutil.go	Adds EROFS OSFeature constant and helpers to ignore/add OS feature variants during platform matching.
pkg/imgutil/transfer.go	Adds EROFS platform variants when configuring transfer stores for pull/push flows.
pkg/imgutil/push/push.go	Sets media-type key prefixes for EROFS layer media types to align ref-key generation.
pkg/cmd/image/remove.go	Uses platformutil matcher (ignoring erofs feature) when enumerating RootFS digests.
pkg/cmd/image/prune.go	Same RootFS matcher adjustment as `image remove`.
pkg/cmd/image/convert.go	Adds EROFS converter integration and related option conflict handling.
pkg/api/types/image_types.go	Introduces `ErofsOptions` in the public options struct.
cmd/nerdctl/image/image_inspect.go	Adjusts default platform behavior to ignore `erofs` OSFeature when platform isn’t specified.
cmd/nerdctl/image/image_convert.go	Adds CLI flags for EROFS conversion and wires them into options.
cmd/nerdctl/image/image_convert_linux_test.go	Adds EROFS conversion tests (guarded by `mkfs.erofs`) and uses `expect.ExitCodeSuccess`.
docs/erofs.md	New documentation explaining prerequisites and how to convert/pull EROFS images.
docs/command-reference.md	Documents new `--erofs*` flags.
go.mod	Adds an indirect dependency required by the new converter path.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+	for _, p := range platformz {
+		var added bool
+		for _, feature := range features {
+			if slices.Contains(p.OSFeatures, feature) {
+				continue
+			}
+			p.OSFeatures = append(p.OSFeatures, feature)
+			added = true
+		}
+		if added {



 		if convertCount > 1 {
-			return errors.New("options --estargz, --zstdchunked, --overlaybd, --nydus and --soci lead to conflict, only one of them can be used")
+			return errors.New("options --estargz, --zstdchunked, --overlaybd, --nydus, --soci and --erofs lead to conflict, only one of them can be used")


AkihiroSuda · 2026-07-09T19:55:34Z

Please try rebasing to pass the CI

Add raw and zstd EROFS conversion support with containerd's EROFS converter. Fixes: containerd#4861 Signed-off-by: Chengyu Zhu <hudson@cyzhu.com>

ChengyuZhu6 · 2026-07-14T03:52:14Z

Please try rebasing to pass the CI

Done.

AkihiroSuda · 2026-07-14T08:58:25Z

Is this change relevant?

platforms.DefaultStrict() fails to match erofs images, so RootFS can't enumerate the rootfs (breaking rmi/prune output).

AkihiroSuda · 2026-07-14T08:58:35Z

Is this change relevant?

platforms.DefaultStrict() fails to match erofs images, so RootFS can't enumerate the rootfs (breaking rmi/prune output).

ChengyuZhu6 marked this pull request as draft May 22, 2026 02:49

sathiraumesh suggested changes May 22, 2026

View reviewed changes

Comment thread cmd/nerdctl/image/image_convert_linux_test.go Outdated

ChengyuZhu6 force-pushed the erofs branch 2 times, most recently from 45e749b to d5a41d0 Compare May 22, 2026 09:30

sathiraumesh suggested changes May 22, 2026

View reviewed changes

Comment thread go.mod

ChengyuZhu6 added this to the v2.3.2 milestone May 22, 2026

ChengyuZhu6 force-pushed the erofs branch 2 times, most recently from d597639 to 1e2babc Compare May 22, 2026 09:39

ChengyuZhu6 requested a review from sathiraumesh May 22, 2026 09:49

AkihiroSuda removed this from the v2.3.2 milestone Jun 11, 2026

ChengyuZhu6 force-pushed the erofs branch 8 times, most recently from 8d9de47 to b85a0ea Compare June 21, 2026 13:43

ChengyuZhu6 added this to the v2.3.4 milestone Jun 21, 2026

ChengyuZhu6 force-pushed the erofs branch from b85a0ea to a7fd687 Compare June 21, 2026 13:53

ChengyuZhu6 marked this pull request as ready for review June 21, 2026 14:00

ChengyuZhu6 requested review from a team, dmcgowan and hsiangkao and removed request for sathiraumesh June 21, 2026 14:00

AkihiroSuda requested a review from ktock June 22, 2026 04:35

ChengyuZhu6 modified the milestones: v2.3.4, v2.4.0 Jun 24, 2026

ChengyuZhu6 force-pushed the erofs branch from a7fd687 to 94835ab Compare June 30, 2026 01:44

AkihiroSuda requested review from Copilot and sathiraumesh July 9, 2026 17:48

Copilot started reviewing on behalf of AkihiroSuda July 9, 2026 17:49 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

image: align erofs convert with containerd

168db2a

Add raw and zstd EROFS conversion support with containerd's EROFS converter. Fixes: containerd#4861 Signed-off-by: Chengyu Zhu <hudson@cyzhu.com>

ChengyuZhu6 force-pushed the erofs branch from 94835ab to 168db2a Compare July 14, 2026 03:51

AkihiroSuda reviewed Jul 14, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

image: align erofs raw/zstd convert behavior with containerd#4927

image: align erofs raw/zstd convert behavior with containerd#4927
ChengyuZhu6 wants to merge 1 commit into
containerd:mainfrom
ChengyuZhu6:erofs

ChengyuZhu6 commented May 22, 2026

Uh oh!

Uh oh!

Uh oh!

sathiraumesh commented May 23, 2026

Uh oh!

ChengyuZhu6 commented Jun 21, 2026

Uh oh!

ChengyuZhu6 commented Jun 21, 2026

Uh oh!

ChengyuZhu6 commented Jun 21, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

AkihiroSuda commented Jul 9, 2026

Uh oh!

ChengyuZhu6 commented Jul 14, 2026

Uh oh!

AkihiroSuda Jul 14, 2026

Uh oh!

ChengyuZhu6 Jul 17, 2026

Uh oh!

AkihiroSuda Jul 14, 2026

Uh oh!

ChengyuZhu6 Jul 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

ChengyuZhu6 commented May 22, 2026

Uh oh!

Uh oh!

Uh oh!

sathiraumesh commented May 23, 2026

Uh oh!

ChengyuZhu6 commented Jun 21, 2026

Uh oh!

ChengyuZhu6 commented Jun 21, 2026

Uh oh!

ChengyuZhu6 commented Jun 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

AkihiroSuda commented Jul 9, 2026

Uh oh!

ChengyuZhu6 commented Jul 14, 2026

Uh oh!

AkihiroSuda Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

ChengyuZhu6 Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

AkihiroSuda Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

ChengyuZhu6 Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ChengyuZhu6 commented Jun 21, 2026 •

edited

Loading